Autogenerated HTML docs for v2.0.0-421-g786a8
diff --git a/git-pull.html b/git-pull.html index a898905..823d365 100644 --- a/git-pull.html +++ b/git-pull.html
@@ -1218,10 +1218,17 @@ </dt> <dd> <p> - The format of a <refspec> parameter is an optional plus - <tt>+</tt>, followed by the source ref <src>, followed - by a colon <tt>:</tt>, followed by the destination ref <dst>. + Specifies which refs to fetch and which local refs to update. + When no <refspec>s appear on the command line, the refs to fetch + are read from <tt>remote.<repository>.fetch</tt> variables instead + (see <a href="git-fetch.html">git-fetch(1)</a>). </p> +<div class="paragraph"><p>The format of a <refspec> parameter is an optional plus +<tt>+</tt>, followed by the source ref <src>, followed +by a colon <tt>:</tt>, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty.</p></div> +<div class="paragraph"><p><tt>tag <tag></tt> means the same as <tt>refs/tags/<tag>:refs/tags/<tag></tt>; +it requests fetching everything up to the given tag.</p></div> <div class="paragraph"><p>The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast-forwarded using <src>. @@ -1233,15 +1240,15 @@ <td class="icon"> <div class="title">Note</div> </td> -<td class="content">If the remote branch from which you want to pull is -modified in non-linear ways such as being rewound and -rebased frequently, then a pull will attempt a merge with -an older version of itself, likely conflict, and fail. -It is under these conditions that you would want to use -the <tt>+</tt> sign to indicate non-fast-forward updates will -be needed. There is currently no easy way to determine -or declare that a branch will be made available in a -repository with this behavior; the pulling user simply +<td class="content">When the remote branch you want to fetch is known to +be rewound and rebased regularly, it is expected that +its new tip will not be descendant of its previous tip +(as stored in your remote-tracking branch the last time +you fetched). You would want +to use the <tt>+</tt> sign to indicate non-fast-forward updates +will be needed for such branches. There is no way to +determine or declare that a branch will be made available +in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch.</td> </tr></table> </div> @@ -1250,56 +1257,25 @@ <td class="icon"> <div class="title">Note</div> </td> -<td class="content">You never do your own development on branches that appear -on the right hand side of a <refspec> colon on <tt>Pull:</tt> lines; -they are to be updated by <em>git fetch</em>. If you intend to do -development derived from a remote branch <tt>B</tt>, have a <tt>Pull:</tt> -line to track it (i.e. <tt>Pull: B:remote-B</tt>), and have a separate -branch <tt>my-B</tt> to do your development on top of it. The latter -is created by <tt>git branch my-B remote-B</tt> (or its equivalent <tt>git -checkout -b my-B remote-B</tt>). Run <tt>git fetch</tt> to keep track of -the progress of the remote side, and when you see something new -on the remote branch, merge it into your development branch with -<tt>git pull . remote-B</tt>, while you are on <tt>my-B</tt> branch.</td> -</tr></table> -</div> -<div class="admonitionblock"> -<table><tr> -<td class="icon"> -<div class="title">Note</div> -</td> <td class="content">There is a difference between listing multiple <refspec> directly on <em>git pull</em> command line and having multiple -<tt>Pull:</tt> <refspec> lines for a <repository> and running +<tt>remote.<repository>.fetch</tt> entries in your configuration +for a <repository> and running a <em>git pull</em> command without any explicit <refspec> parameters. -<refspec> listed explicitly on the command line are always +<refspec>s listed explicitly on the command line are always merged into the current branch after fetching. In other words, -if you list more than one remote refs, you would be making -an Octopus. While <em>git pull</em> run without any explicit <refspec> -parameter takes default <refspec>s from <tt>Pull:</tt> lines, it -merges only the first <refspec> found into the current branch, -after fetching all the remote refs. This is because making an +if you list more than one remote ref, <em>git pull</em> will create +an Octopus merge. On the other hand, if you do not list any +explicit <refspec> parameter on the command line, <em>git pull</em> +will fetch all the <refspec>s it finds in the +<tt>remote.<repository>.fetch</tt> configuration and merge +only the first <refspec> found into the current branch. +This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one-go by fetching more than one is often useful.</td> </tr></table> </div> -<div class="paragraph"><p>Some short-cut notations are also supported.</p></div> -<div class="ulist"><ul> -<li> -<p> -<tt>tag <tag></tt> means the same as <tt>refs/tags/<tag>:refs/tags/<tag></tt>; - it requests fetching everything up to the given tag. -</p> -</li> -<li> -<p> -A parameter <ref> without a colon merges <ref> into the current - branch, - and updates the remote-tracking branches (if any). -</p> -</li> -</ul></div> </dd> </dl></div> </div>
